Artemis Trouble Ticket API - TMF621

API Overview

The TMF621 Trouble Ticket API provides a standardized interface for partners to raise, track, and manage trouble tickets related to broadband and voice services. It enables communication of service issues to PXC and supports both appointed and non-appointed fault scenarios.

This API aligns with TM Forum’s TMF621 v5.0.0 specification and forms part of the Strategic Assurance Management (SAM) platform, which aims to deliver a consistent and automated assurance experience across all strategic products (e.g., FTTP, SOGEA & Single Line Voice(VOIP)).

Disclaimer

Patch requests (including amendments and cancellations) that contain a free‑text TMF621 note are routed for manual review and handling. This is to ensure the information is assessed before it is passed to downstream systems and, where applicable, shared with the supplier. As a result, requests that include a note may take longer to process than standard (note‑free) patch requests.

For time‑sensitive operations, partners are strongly advised not to include a free‑text note, as the manual handling step can delay execution and increase the risk that the request is processed after supplier control points (for example, the supplier Point of No Return). Once these control points are reached, amendments may be rejected, tickets may be cancelled and some actions may become chargeable in line with supplier rules.

This recommendation applies in particular to time‑critical requests such as:

• Cancellation requests
• Appointment rescheduling / appointment amendments
• Engineer effort authorisation
• End‑user details updates

Where additional context is required, provide it via two separate patch operations.

Do not reuse sample values. Replace all identifiers, phone numbers, and contact details with your own test/production data.

All reserved terms in the examples are provided with a camel case format (i.e. "role": "relatedAccount”). All TMF metadata attributes are in Pascal case format (i.e. "@baseType": "ContactMedium”).

Key Capabilities

• Retrieve list of Trouble Ticket Specifications-
• Retrieve details of a Trouble Ticket Specification-
• Raise a new Trouble Ticket with fault details and attachments-
• Modify existing tickets (e.g., status, notes, appointment references)-
• Retrieve current ticket status and metadata-
• Receive event-driven updates (e.g., status changes, resolution notifications)

Authentication & Authorisation

Access is secured using OAuth 2.0 JWT issued by PXC’s partner identity platform. Only authenticated and authorized partners may access the API.

Standards Alignment

This API conforms to the TMF621 resource model and operational semantics, supporting core operations:

GET /troubleTicketSpecification/{id}
GET /troubleTicketSpecification
POST /troubleTicket
PATCH /troubleTicket/{id}
GET /troubleTicket/{id}
GET /troubleTicket
Notifications: TMF621-compliant event types

API Fundamentals

The TMF621 Trouble Ticket API supports the creation, update, and retrieval of assurance-related tickets via RESTful endpoints. It is designed according to TMF630 guidelines and is implemented with layered architecture to ensure scalability, traceability, and partner interoperability.

The API is built on REST principles using standard HTTP methods (POST, PATCH, GET) and uses JSON payloads for both requests and responses. Key resource types such as TroubleTicket, TroubleTicketSpecification, Note, and Attachment follow TMF schema patterns and support polymorphic extension via @type, @baseType, and @schemaLocation.

All interactions are secured via OAuth 2.0 JWT authentication issued by the Artemis partner identity platform. Partner-specific traceability is supported via optional Correlation-ID (UUID v4 (RFC 4122)) headers, and data minimization is achieved using field projection and filtering query parameters. If passed, the Correlation-ID will be returned to the consumer in the API response; otherwise a new Correlation-ID will be used to track the transaction.

This API enables seamless integration between external partners and internal processes through MuleSoft orchestration.

TMF Metadata Fields

TMF APIs use a set of metadata fields to support polymorphism, inheritance, and resource linking.

• @type: Specifies the concrete type of the object, especially when it is an extension of a base TMF resource. For example, @type: PartnerTroubleTicket indicates a specialization of the standard TroubleTicket.-
• @baseType: Indicates the base TMF resource from which the object inherits, such as TroubleTicket. This is useful for deserialization and tooling.-
• href: A full URI that points to the canonical location of the resource (e.g., GET /troubleTicket/{id}). It is mandatory in all GET responses for top-level and referenced resources, allowing clients to retrieve the full object via follow-up calls.-
• @schemaLocation (optional): Provides the URL of the JSON schema that defines the structure of the resource, mainly for validation or developer tooling.

These metadata fields are generally not required in POST or PATCH requests, but are mandatory in GET responses for compliance with TMF Open API standards.

Schema Extensions

To accommodate the current requirements, the API was extended using the @type field for custom classifications and the troubleTicketCharacteristic array for dynamic attributes. This supports flexible modelling of fault categories and appointment metadata without altering the base schema.

Where necessary, a subset of relatedEntity and relatedParty attributes were extended to carry additional context, such as Product ID, Access CASR, or appointment reference.

Authentication and Authorisation

The TMF621 Trouble Ticket API is hosted in Azure and exposed via the PXC API Gateway. It uses the OAuth2 protocol for client authentication using a client_id and client_secret. Once authenticated, a client receives a bearer token, which must be passed in the Authorization header for all API requests.

BillingAccountis required as a relatedEntity for authorization.